Skunkware 5/Skunkware 5.iso/man/cat.1/mpeg_encode.1

Text File | 1995-07-25 | 22KB | 463 lines

     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



     NNNNAAAAMMMMEEEE
          mpeg_encode - mpeg-1 video stream encoder

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          mmmmppppeeeegggg____eeeennnnccccooooddddeeee [ ----ssssttttaaaatttt ssssttttaaaatttt____ffffiiiilllleeee ] [ ----qqqquuuuiiiieeeetttt nnnnuuuummmm____sssseeeeccccoooonnnnddddssss ] [ ----
          nnnnoooo____ffffrrrraaaammmmeeee____ssssuuuummmmmmmmaaaarrrryyyy ] [ ----ggggoooopppp ggggoooopppp____nnnnuuuummmm ] [ ----ccccoooommmmbbbbiiiinnnneeee____ggggooooppppssss ] [ ----
          ffffrrrraaaammmmeeeessss ffffiiiirrrrsssstttt____ffffrrrraaaammmmeeee llllaaaasssstttt____ffffrrrraaaammmmeeee ] [ ----ccccoooommmmbbbbiiiinnnneeee____ffffrrrraaaammmmeeeessss ] [ ----nnnniiiicccceeee
          ] [ ----mmmmaaaaxxxx____mmmmaaaacccchhhhiiiinnnneeeessss nnnnuuuummmm____mmmmaaaacccchhhhiiiinnnneeeessss ] [ ----ssssnnnnrrrr ] ppppaaaarrrraaaammmm____ffffiiiilllleeee

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          mmmmppppeeeegggg____eeeennnnccccooooddddeeee produces an MPEG-1 video stream.  param_file is
          a parameter file which includes a list of input files and
          other parameters.  The file is described in detail below.
          The -gop, -combine_gops, -frames, and -combine_frames
          options are all exclusive.

     OOOOPPPPTTTTIIIIOOOONNNNSSSS
          ----ssssttttaaaatttt ssssttttaaaatttt____ffffiiiilllleeee : causes the encoder to append the
               statistics to the file _s_t_a_t__f_i_l_e.  In any case, the
               statistics are output to stdout.  The statistics use
               the following abbreviations:  bits per block (bpb),
               bits per frame (bpf), seconds per frame (spf), and bits
               per second (bps).

          ----qqqquuuuiiiieeeetttt nnnnuuuummmm____sssseeeeccccoooonnnnddddssss : causes the program to not report
               remaining time for at least num_seconds seconds.  A
               negative values tells the program not to report at all.
               0 is the default (reports once after each frame).  Note
               that the time remaining is an estimate and does not
               take into account time to read in frames.

          ----nnnnoooo____ffffrrrraaaammmmeeee____ssssuuuummmmmmmmaaaarrrryyyy : prevents the program from printing a
               summary line for each frame

          ----ggggoooopppp ggggoooopppp____nnnnuuuummmm : causes the encoder to only encode the
               numbered GOP (first GOP is 0).  The parameter file is
               the same as for normal usage.  The output file will be
               the normal output file with the suffix ".gop.<gop_num>"
               No sequence info is output.

          ----ccccoooommmmbbbbiiiinnnneeee____ggggooooppppssss : causes the encoder to simply combine some
               GOP files into a single MPEG stream.  A sequence
               header/ender are inserted.  In this case, the parameter
               file need only contain the YUV_SIZE value, an output
               file, and perhaps a list of input GOP files (see
               below).

          ----ffffrrrraaaammmmeeeessss ffffiiiirrrrsssstttt____ffffrrrraaaammmmeeee llllaaaasssstttt____ffffrrrraaaammmmeeee : causes the encoder to only
               encode the frames from first_frame to last_frame,
               inclusive.  The parameter file is the same as for
               normal usage.  The output will be placed in separate
               files, one per frame, with the file names being the



     Page 1                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



               normal output file with the suffix ".frame.<frame num>"
               No GOP header information is output.  (Thus, the
               parameter file need not include the GOP_SIZE value)

          ----ccccoooommmmbbbbiiiinnnneeee____ffffrrrraaaammmmeeeessss : causes the encoder to simply combine some
               frames into a single MPEG stream.  Sequence and GOP
               headers are inserted appropriately.  In this case, the
               parameter file need only contain the YUV_SIZE value,
               the GOP_SIZE value, an output file, and perhaps a list
               of frame files (see below).

          ----nnnniiiicccceeee : causes the program to run any remote processes
               'nicely.'  This is only relevant if the program is
               using parallel encoding.  (see 'man nice.')

          ----mmmmaaaaxxxx____mmmmaaaacccchhhhiiiinnnneeeessss nnnnuuuummmm____mmmmaaaacccchhhhiiiinnnneeeessss : causes the program to use no
               more than num_machines machines as slaves for use in
               parallel encoding.

          ----ssssnnnnrrrr : print the signal-to-noise ratio.  Prints SNR (Y U V)
               and peak SNR (Y U V) for each frame.  In summary,
               prints averages of luminance only (Y).  SNR is defined
               as 10*log(variance of original/variance of error).
               Peak SNR is defined as 20*log(255/RMSE).  Note that the
               encoder will run a little slower if you want it to
               print the SNR.


     PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR FFFFIIIILLLLEEEE
          The parameter file MUST contain the following lines (except
          when using the -combine_gops or -combine_frames options):

               PATTERN <pattern>

               OUTPUT <output file>

               INPUT_DIR <directory>
                    all input files must reside in this directory.  If
                    you want to refer to the current directory, use
                    '.' (an empty INPUT_DIR value would refer to the
                    root directory).

               INPUT
                    This line must be followed by a list of the input
                    files (in display order) and then the line
                         END_INPUT
                    There are three types of lines between INPUT and
                    END_INPUT.  First, a line may simply be the name
                    of an input file.  Secondly, the line may be of
                    the form
                         <single_star_expr> [x-y]
                    single_star_expr can have a single '*' in it.  It



     Page 2                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



                    is replaced by all the numbers between x and y
                    inclusive.  So, for example, the line
                         tennis*.ppm [12-15]
                    is replaced by tennis12.ppm, tennis13.ppm,
                    tennis14.ppm, tennis15.ppm.  Uniform zero-padding
                    occurs, as well.  For example, the line
                         football.*.ppm [001-130]
                    is replaced by football.001.ppm, football.002.ppm,
                    ..., football.009.ppm, football.010.ppm, ...,
                    football.130.ppm.  The third type of line is:
                         <single_star_expr> [x-y+s]
                    Where the line is treated exactly as above, except
                    that we skip by s.  Thus, the line
                         football.*.ppm [001-130+4]
                    is replaced by football.001.ppm, football.005.ppm,
                    football.009.ppm, football.013.ppm, etc.

               BASE_FILE_FORMAT <YUV or PPM or PNM>
                    All the input files must be converted to YUV, PNM
                    or PPM format.  This line specifies which of the
                    three formats (actually PPM is a subset of PNM).
                    In the YUV format, the U and V components are
                    subsampled 4:1.  The reason for having a separate
                    PPM option is for simplicity.  If your files are
                    RAWBITS ppm files, then use the PPM option rather
                    than the PNM.  Also, depending on the system, file
                    reads will go much faster with the PPM option (as
                    opposed to PNM).

               INPUT_CONVERT <conversion command>
                    You must specify how to convert a file to the base
                    file format.  In the conversion command, each '*'
                    is replaced by the filename (the items listed
                    between INPUT and END_INPUT).  If no conversion is
                    necessary, then you would just say:
                         INPUT_CONVERT *
                    If you had a bunch of gif files, you might say:
                         INPUT_CONVERT giftoppm *
                    If you have a bunch of separate a.Y, a.U, and a.V
                    files, then you might say:
                         INPUT_CONVERT cat *.Y *.U *.V

               GOP_SIZE <n>
                    n is roughly the number of frames in a Group of
                    Pictures (roughly because a GOP must begin with an
                    I-frame)

               SLICES_PER_FRAME <n>
                    n is roughly the number of slices per frame.
                    Note, at least one MPEG player may complain if
                    slices do not start at the left side of an image.
                    To ensure this does not happen, make sure the



     Page 3                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



                    number of rows is divisible by SLICES_PER_FRAME.

               PIXEL <FULL or HALF>
                    use half-pixel motion vectors, or only full-pixel
                    ones

               RANGE <n>
                    use a search range of +/- n pixels

               PSEARCH_ALG <algorithm>
                    algorithm must be one of {EXHAUSTIVE, TWOLEVEL,
                    SUBSAMPLE, LOGARITHMIC}.  Tells what kind of
                    search procedure should be used for P-frames.
                    Exhaustive gives the best compression, but
                    logarithmic is the fastest.  You select the
                    desired combination of speed and compression.
                    TWOLEVEL is an exhaustive full-pixel search,
                    followed by a local half- pixel search around the
                    best full-pixel vector (the PIXEL option is
                    ignored for this search algorithm).

               BSEARCH_ALG <algorithm>
                    algorithm must be one of {SIMPLE, CROSS2,
                    EXHAUSTIVE}.  Tells what kind of search procedure
                    should be used for B-frames.  Simple means find
                    best forward and backward vectors, then
                    interpolate.  Cross2 means find those two vectors,
                    then see what backward vector best matches the
                    best forward vector, and vice versa.  Exhaustive
                    does an n-squared search and is EXTREMELY slow in
                    relation to the others (Cross2 is about twice as
                    slow as Simple).

               IQSCALE <n>
                    use n as the qscale for I-frames

               PQSCALE <n>
                    use n as the qscale for P-frames

               BQSCALE <n>
                    use n as the qscale for B-frames

               REFERENCE_FRAME <ORIGINAL or DECODED>
                    If ORIGINAL is specified, then the original images
                    are used when computing motion vectors.  To be
                    more accurate, use DECODED, in which the decoded
                    images are used.  This should increase the quality
                    of the image, but will take a bit longer to
                    encode.
               The following lines are optional:

                    FORCE_I_ALIGN



     Page 4                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



                         This option is only relevant for parallel
                         execution (see below).  It forces each
                         processor to encode a block of N frames,
                         where N must be a multiple of the pattern
                         length.  Since the first frame in any pattern
                         is an I-frame, this forces each block encoded
                         by a processor to begin with an I-frame.
                    foo


     NNNNOOOOTTTTEEEESSSS
          If the BASE_FILE_FORMAT is YUV, then the parameter file must
          contain:
               YUV_SIZE <w>x<h>
          where w = width, h = height (in pixels) of image

          If the -combine-gops option is used, then only the YUV_SIZE
          and OUTPUT values need be specified in the parameter file.
          In addition, the parameter file may specify input GOP files
          in the same manner as normal input files -- except instead
          of using INPUT_DIR, INPUT, and END_INPUT, use GOP_INPUT_DIR,
          GOP_INPUT, and GOP_END_INPUT.  If no input GOP files are
          specified, then the default is to use the output file name
          with suffix ".gop.<gop_num>" starting from 0 as the input
          files.

          If the -combine-frames option is used, then only the
          YUV_SIZE, GOP_SIZE, and OUTPUT values need be specified in
          the parameter file.  In addition, the parameter file may
          specify input frame files in the same manner as normal input
          files -- except instead of using INPUT_DIR, INPUT, and
          END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and
          FRAME_END_INPUT.  If no input frame files are specified,
          then the default is to use the output file name with suffix
          ".frame.<frame_num>" starting from 0 as the input files.

          Any number of spaces and tabs may come between each option
          and value.  Lines beginning with '#' are ignored.  Any other
          lines are ignored except for those between INPUT and
          END_INPUT.  This allows you to use the same parameter file
          for normal usage and for -combine_gops and -combine_frames.

          The encoder is case-sensitive so, except for file names and
          directories, everything should be in upper case.

          The lines may appear in any order, except the following
          exceptions.  INPUT must appear before END_INPUT  (also,
          GOP_INPUT before GOP_END_INPUT and FRAME_INPUT before
          FRAME_END_INPUT).  All lines between INPUT and END_INPUT
          must be the frames in play order.





     Page 5                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



     PPPPAAAARRRRAAAALLLLLLLLEEEELLLL OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN
          The encoder may be run on multiple machines at once.  To do
          so, add a line "PARALLEL" in the parameter file, followed by
          a listing, one machine per line, then "END_PARALLEL".  Each
          of the lines should be in one of two forms.  If the machine
          has access to the file server, then the line should be:

               <machine> <user> <executable>

          The executable is normally mpeg_encode (you may need to give
          the complete path if you've built for different
          architectures).  If the machine is a remote machine, then
          the line should be:

               REMOTE <machine> <user> <executable> <parameter file>

          Full paths should generally be used when describing
          executables and parameter files.  This INCLUDES the
          parameter file given as an argument to the original call to
          mpeg_encode.  Also, .rhosts files on the appropriate
          machines should have the appropriate information.

          The encoder will use the original machine for the master and
          I/O server processes, and uses the listed machines as slaves
          to do the computation.

          Optional lines are

          RSH <remote shell command>
               The encoder uses the remote shell command to start
               processes on other machines.  The default command is
               'rsh.'  If your machine supports a different command,
               specify it here.

          PARALLEL_TEST_FRAMES <n>
               n is the number of frames to encode initially on each
               processor

          PARALLEL_TIME_CHUNKS <t>
               subsequently, each slave processor will be asked to
               encode for approximately t seconds.  Smaller values of
               <t> increase communication, but improve load balancing.

               The default values for these two options are n = 3
                    frames and t = 30 seconds.

          PARALLEL_PERFECT
               If this line is present, then scheduling is done on the
               assumption that work distribution will be perfectly
               even -- meaning that each machine is about the same
               speed.  The frames will simply be divided up evenly
               between the processors.  This has the advantage of very



     Page 6                                         (printed 11/26/93)






     MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((11118888 OOOOccccttttoooobbbbeeeerrrr 1111999999993333))))   MMMMPPPPEEEEGGGG____EEEENNNNCCCCOOOODDDDEEEE((((1111))))



               minimal scheduling overhead, but is obviously wrong if
               machines have varying speeds, or if the network load
               makes performance uneven.
          Please note that the parallel code has not been well-tested
          and is not very fault-tolerant (if a slave process goes
          down, nothing works).  Future versions of the encoder will
          support parallel execution better.


     AAAAUUUUTTTTHHHHOOOORRRRSSSS
          Kevin Gong - University of California, Berkeley,
               [e-mail]

          Ketan Patel - University of California, Berkeley,
               [e-mail]

          Dan Wallach - University of California, Berkeley,
               [e-mail]

     BBBBUUUUGGGGSSSS
          No known bugs.


































     Page 7                                         (printed 11/26/93)